home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / share / perl / 5.10.0 / Pod / Simple / PullParserToken.pm < prev    next >
Encoding:
Perl POD Document  |  2009-06-26  |  3.2 KB  |  139 lines
  1.  
  2. require 5;
  3. package Pod::Simple::PullParserToken;
  4.  # Base class for tokens gotten from Pod::Simple::PullParser's $parser->get_token
  5. @ISA = ();
  6. $VERSION = '2.02';
  7. use strict;
  8.  
  9. sub new {  # Class->new('type', stuff...);  ## Overridden in derived classes anyway
  10.   my $class = shift;
  11.   return bless [@_], ref($class) || $class;
  12. }
  13.  
  14. sub type { $_[0][0] }  # Can't change the type of an object
  15. sub dump { Pod::Simple::pretty( [ @{ $_[0] } ] ) }
  16.  
  17. sub is_start { $_[0][0] eq 'start' }
  18. sub is_end   { $_[0][0] eq 'end'   }
  19. sub is_text  { $_[0][0] eq 'text'  }
  20.  
  21. 1;
  22. __END__
  23.  
  24. sub dump { '[' . _esc( @{ $_[0] } ) . ']' }
  25.  
  26. # JUNK:
  27.  
  28. sub _esc {
  29.   return '' unless @_;
  30.   my @out;
  31.   foreach my $in (@_) {
  32.     push @out, '"' . $in . '"';
  33.     $out[-1] =~ s/([^- \:\:\.\,\'\>\<\"\/\=\?\+\|\[\]\{\}\_a-zA-Z0-9_\`\~\!\#\%\^\&\*\(\)])/
  34.       sprintf( (ord($1) < 256) ? "\\x%02X" : "\\x{%X}", ord($1))
  35.     /eg;
  36.   }
  37.   return join ', ', @out;
  38. }
  39.  
  40.  
  41. __END__
  42.  
  43. =head1 NAME
  44.  
  45. Pod::Simple::PullParserToken -- tokens from Pod::Simple::PullParser
  46.  
  47. =head1 SYNOPSIS
  48.  
  49. Given a $parser that's an object of class Pod::Simple::PullParser
  50. (or a subclass)...
  51.  
  52.   while(my $token = $parser->get_token) {
  53.     $DEBUG and print "Token: ", $token->dump, "\n";
  54.     if($token->is_start) {
  55.       ...access $token->tagname, $token->attr, etc...
  56.  
  57.     } elsif($token->is_text) {
  58.       ...access $token->text, $token->text_r, etc...
  59.     
  60.     } elsif($token->is_end) {
  61.       ...access $token->tagname...
  62.     
  63.     }
  64.   }
  65.  
  66. (Also see L<Pod::Simple::PullParser>)
  67.  
  68. =head1 DESCRIPTION
  69.  
  70. When you do $parser->get_token on a L<Pod::Simple::PullParser>, you should
  71. get an object of a subclass of Pod::Simple::PullParserToken.
  72.  
  73. Subclasses will add methods, and will also inherit these methods:
  74.  
  75. =over
  76.  
  77. =item $token->type
  78.  
  79. This returns the type of the token.  This will be either the string
  80. "start", the string "text", or the string "end".
  81.  
  82. Once you know what the type of an object is, you then know what
  83. subclass it belongs to, and therefore what methods it supports.
  84.  
  85. Yes, you could probably do the same thing with code like
  86. $token->isa('Pod::Simple::PullParserEndToken'), but that's not so
  87. pretty as using just $token->type, or even the following shortcuts:
  88.  
  89. =item $token->is_start
  90.  
  91. This is a shortcut for C<< $token->type() eq "start" >>
  92.  
  93. =item $token->is_text
  94.  
  95. This is a shortcut for C<< $token->type() eq "text" >>
  96.  
  97. =item $token->is_end
  98.  
  99. This is a shortcut for C<< $token->type() eq "end" >>
  100.  
  101. =item $token->dump
  102.  
  103. This returns a handy stringified value of this object.  This
  104. is useful for debugging, as in:
  105.  
  106.   while(my $token = $parser->get_token) {
  107.     $DEBUG and print "Token: ", $token->dump, "\n";
  108.     ...
  109.   }
  110.  
  111. =back
  112.  
  113. =head1 SEE ALSO
  114.  
  115. My subclasses:
  116. L<Pod::Simple::PullParserStartToken>,
  117. L<Pod::Simple::PullParserTextToken>, and
  118. L<Pod::Simple::PullParserEndToken>.
  119.  
  120. L<Pod::Simple::PullParser> and L<Pod::Simple>
  121.  
  122. =head1 COPYRIGHT AND DISCLAIMERS
  123.  
  124. Copyright (c) 2002 Sean M. Burke.  All rights reserved.
  125.  
  126. This library is free software; you can redistribute it and/or modify it
  127. under the same terms as Perl itself.
  128.  
  129. This program is distributed in the hope that it will be useful, but
  130. without any warranty; without even the implied warranty of
  131. merchantability or fitness for a particular purpose.
  132.  
  133. =head1 AUTHOR
  134.  
  135. Sean M. Burke C<sburke@cpan.org>
  136.  
  137. =cut
  138.  
  139.